home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / source.lha / Geomview / doc / oogltour < prev    next >
Text File  |  1992-06-15  |  19KB  |  543 lines
  1. Tutorial: The OOGL Geom File Formats 
  2.         (and Geomview along the way)
  3.  
  4. OOGL stands for Object Oriented Graphics Library.  An OOGL object is
  5. called a Geom. There is a text file format for each kind of Geom. You
  6. can load a text file into any program that uses OOGL. Geomview is an
  7. interactive 3D object viewer for Silicon Graphics machines built on
  8. top of the OOGL. (We will soon have incarnations of Geomview and OOGL
  9. available for Sun and Next machines.) There are Geomview notes in
  10. brackets interspersed throughout this guide telling you what to do in
  11. Geomview to see what we're talking about. Later notes assume you both
  12. know how to do and have done what previous notes told you about. All
  13. of the files referred to in this document should be in the directory
  14. of sample OOGL files that comes with Geomview.
  15.  
  16. The OOGL man page is a complete reference for the syntax of file
  17. formats. This tutorial is an attempt to lead you more gently into the
  18. world of OOGL.
  19.  
  20. ----------------------------------------------------------------------
  21. ----------------------------------------------------------------------
  22.  
  23.                 QUAD
  24.  
  25. We start with a very simple object: a square. Specifically, the unit
  26. square in the xy plane at z=0.
  27. ----------------------------------------------------------------------
  28. "square.quad":
  29.  
  30. QUAD
  31. -1 -1 0 
  32. 1 -1 0
  33. 1 1 0
  34. -1 1 0
  35. ----------------------------------------------------------------------
  36. The header "QUAD" identifies the file type.  (You can also use the
  37. header "POLY" for this type for historical reasons.)  A QUAD file is a
  38. list of 4*n vertices where n is the number of quadrilaterals. This
  39. file only contains one quadrilateral.  You can also use this format to
  40. specify triangles: just use a degenerate quadrilateral where two of
  41. the four vertices are identical.  The vertices in this file are
  42. simple: just the x,y, and z coordinates of the point.
  43.  
  44. [GEOMVIEW: Type "geomview square.quad" from a shell window on a
  45. Silicon Graphics Iris. Spin the square around with the left mouse
  46. after geomview loads it. Feel free to play with geomview a while if
  47. the fancy strikes you during this tutorial.  ]
  48.  
  49. The next file has more complex vertices that include a color with a point. 
  50. ----------------------------------------------------------------------
  51. "csquare.quad":
  52.  
  53. CQUAD
  54. -1 -1 0        1 0 0 1
  55. 1 -1 0        0 1 0 1
  56. 1 1 0        0 1 0 1
  57. -1 1 0        1 0 0 1
  58. ----------------------------------------------------------------------
  59. It's got the same points as the previous square, but with two red and
  60. two green corners. The header is now "CQUAD" to indicate that its
  61. vertices contain color information as well as point information.
  62. Colors are specified by (r,g,b,a) 4-tuples of floating point numbers
  63. between 0 and 1. Any color that can be displayed on a computer screen
  64. can be encoded by some combination of red, green and blue. The fourth
  65. component, alpha, represents opacity: 0 is transparent and 1 is
  66. opaque. The current SGI GL version of geomview ignores alpha
  67. information, but the Renderman version will pay attention to it.
  68.  
  69.  
  70. [geomview: Delete the current object by hitting the Delete button.  To
  71. load csquare.quad, hit the Load Button and type "csquare.quad" (hit
  72. RETURN when you're done typing) into the popup box that appears. (If
  73. you're browsing and are not sure about file names, you can use the
  74. File Browser Button to look around in a directory.)
  75.  
  76. You're probably wondering why it's all one color.  The default shading
  77. mode is flat shading, where each polygon or polygonal face is the same
  78. color. The other two shading modes, constant and smooth, will both
  79. display multicolored faces where the colors smoothly interpolated
  80. between vertices. Constant shading ignores all lighting information,
  81. while smooth shading interpolates lighting as well as coloring between
  82. the vertices.
  83.  
  84. To change shading mode, first open up the Appearance panel by clicking
  85. on the Appearance line in the More Panels browser.  Now switch from
  86. mode to mode by clicking on different lines in the Shading browser.
  87. ]
  88.  
  89.  
  90. Time to move on to bigger and better things. 
  91.  
  92. "dodec.quad":
  93.  
  94. QUAD
  95. 0 0 0.794654 0 0.491123 0.794654 0.356822 0.491123 0.794654 0.467086 0.151765 0.794654
  96. 0 0 0.794654 -0.467086 0.151765 0.794654 -0.356822 0.491123 0.794654 4.89153e-09 0.491123 0.794654
  97. 0 0 0.794654 -0.288675 -0.397327 0.794654 -0.57735 -0.187593 0.794654 -0.467086 0.151766 0.794654
  98. 0 0 0.794654 0.288675 -0.397327 0.794654 4.36694e-09 -0.607062 0.794654 -0.288675 -0.397327 0.794654
  99. 0 0 0.794654 0.467086 0.151766 0.794654 0.57735 -0.187592 0.794654 0.288675 -0.397327 0.794654
  100. 0 0.710761 0.35538 0 0.491123 0.794654 -0.356822 0.491123 0.794654 -0.467086 0.642889 0.491123
  101.     .
  102.     .
  103.     .
  104.  < 55 lines of numbers deleted>
  105.  
  106.  
  107. Now we've got a more interesting object: a dodecahedron.  Since
  108. dodecahedra have 5-sided faces, each of its 12 faces is actually made out
  109. of 5 quadrilaterals for a total of 20 quadrilaterals in this Quad object.
  110.  
  111. [geomview: 
  112. Delete the square and load "dodec.quad". Since the 5
  113. quadilaterals on each face all fit together perfectly, the fact that
  114. there are indeed many of them on each face is only apparent when the
  115. edges are drawn. To turn on edge drawing, hit the Edges button on
  116. the Appearance panel.
  117. ]
  118.  
  119.  
  120.                 OFF
  121.  
  122. There is a much more efficient way of representing a dodecahedron.
  123.  
  124. "dodec.off":
  125.  
  126. OFF
  127. 20 12 30
  128.     1.214124 0.000000 1.589309
  129.     0.375185 1.154701 1.589309
  130.     -0.982247 0.713644 1.589309
  131.     -0.982247 -0.713644 1.589309
  132.     0.375185 -1.154701 1.589309
  133.     1.964494 0.000000 0.375185
  134.     0.607062 1.868345 0.375185
  135.     -1.589309 1.154701 0.375185
  136.     -1.589309 -1.154701 0.375185
  137.     0.607062 -1.868345 0.375185
  138.     1.589309 1.154701 -0.375185
  139.     -0.607062 1.868345 -0.375185
  140.     -1.964494 0.000000 -0.375185
  141.     -0.607062 -1.868345 -0.375185
  142.     1.589309 -1.154701 -0.375185
  143.     0.982247 0.713644 -1.589309
  144.     -0.375185 1.154701 -1.589309
  145.     -1.214124 0.000000 -1.589309
  146.     -0.375185 -1.154701 -1.589309
  147.     0.982247 -0.713644 -1.589309
  148.     5 0 1 2 3 4
  149.     5 0 5 10 6 1
  150.     5 1 6 11 7 2
  151.     5 2 7 12 8 3
  152.     5 3 8 13 9 4
  153.     5 4 9 14 5 0
  154.     5 15 10 5 14 19
  155.     5 16 11 6 10 15
  156.     5 17 12 7 11 16
  157.     5 18 13 8 12 17
  158.     5 19 14 9 13 18
  159.     5 19 18 17 16 15
  160.  
  161. The "OFF" header tells us it's a polylist file. The second line in
  162. the file tells us that there are 20 vertices, 12 faces, and 30 edges.
  163. (The OOGL libraries presently don't use the edges value, so you can
  164. just use 0 if you don't happen know the number of edges.)  The next 20
  165. lines give a list of vertices. The last 12 lines specify the faces:
  166. the first number is the number of vertices in that face. Since our
  167. polyhedron happens to be regular, all faces have the same number of
  168. vertices (in this case, 5).  The rest of the numbers on the line are
  169. indices into the above list of vertices.
  170.  
  171. Besides being far more compact, the Polylist file format embeds
  172. connectivity information in the Geom.  OOGL has no way of knowing
  173. whether any two quadrilaterals in a Quad object are connected.  But
  174. with a Polylist, OOGL can interpolate normals across connected faces.
  175. The normals of an object are used to calculate shading information.
  176. Interpolated normals make an object look smooth instead of faceted.
  177. This is often desirable if you are trying to approximate a curved
  178. surface by breaking it up into small pieces.
  179.  
  180. [geomview: 
  181. Go ahead and load "dodec.off" without deleting the other one.  Now
  182. you've got two Geoms in your world.  Most actions apply to the
  183. currently picked object. When you start up geomview, the currently
  184. picked object is the whole world. You can independently control any
  185. object in the world by picking it as the target of your actions.
  186. Double-clicking the right mouse button when the mouse is over an
  187. object picks it: double-clicking the right mouse over empty space
  188. picks the whole world. You can also pick objects by clicking on the
  189. appropriate line in the Object browser.
  190.  
  191. The two dodecahedra are probably superimposed.  Pick one of them as
  192. your target, click on the "Translate" line in the motion browser, and
  193. move the picked object away from the center of the world with the left
  194. mouse.  (To return to "Rotate" mode, click the appropriate line in the
  195. motion browser.)
  196.  
  197. Now pick the whole world again and draw the normals by hitting the
  198. "Normals" button on the Appearance panel. Switch between Flat and
  199. Smooth Shading modes (by clicking in the Shading browser) and notice
  200. that the Polylist changes but the Quad doesn't.  
  201.  
  202. Sometimes using the mouse to click on browser lines and buttons is
  203. cumbersome. The bracketed characters shown on the control panels are
  204. keyboard shortcuts that duplicate the effect of using the mouse to
  205. click on that line or button. For instance, "an" (the "a" stands for
  206. "appearance") toggles drawing normals and "t" switches the motion to
  207. translation.  In a further shortcut, you can use the prefix of an
  208. object ("g" or "c" followed by a number, as shown in brackets in the
  209. Object browser) before most commands to simultaneously pick an object
  210. and do some action to it. For instance, "g0r" lets you immediately
  211. rotate the world.
  212.  
  213. ]
  214.  
  215.  
  216. Let's compare two ways of coloring a Polylist.
  217.  
  218. facecube.off:
  219.  
  220. # off file with per face color
  221. OFF
  222. 8 6 12
  223.      1.0 1.0 1.0 
  224.      1.0 1.0 -1.0 
  225.      1.0 -1.0 1.0 
  226.      1.0 -1.0 -1.0 
  227.      -1.0 1.0 1.0 
  228.      -1.0 1.0 -1.0 
  229.      -1.0 -1.0 1.0 
  230.      -1.0 -1.0 -1.0 
  231.      4 0 2 3 1  .05 .8 .1 .75
  232.      4 4 5 7 6  .2 .05 .8 .75
  233.      4 0 4 6 2  .9 .9 .02 .75
  234.      4 1 3 7 5  .0 .7 .4 .75
  235.      4 0 1 5 4  .1 .4 .7 .75
  236.      4 2 6 7 3  .7 .7 0 .75
  237.  
  238. vertcube.off:
  239.  
  240. # off file with per vertex colors
  241. COFF
  242. 8 6 12
  243.      1.0 1.0 1.0     .05 .8 .1 .75
  244.      1.0 1.0 -1.0    .2 .05 .8 .75 
  245.      1.0 -1.0 1.0    .9 .9 .02 .75 
  246.      1.0 -1.0 -1.0     .0 .7 .4 .75
  247.      -1.0 1.0 1.0     .1 .4 .7 .75
  248.      -1.0 1.0 -1.0     .7 .7 0 .75
  249.      -1.0 -1.0 1.0     0. 0. 0. .75
  250.      -1.0 -1.0 -1.0     1. 1. 1. .75    
  251.      4 0 2 3 1  
  252.      4 4 5 7 6  
  253.      4 0 4 6 2  
  254.      4 1 3 7 5  
  255.      4 0 1 5 4  
  256.      4 2 6 7 3  
  257.  
  258. Everything following a "#" is a comment for humans to read and is
  259. ignored by OOGL. The header for a plain Polylist file is optional, but
  260. if you have anything besides points in a vertex you do need a proper
  261. header.  The object is the unit cube, which has 8 vertices, 6 faces,
  262. and 12 edges.  The first has per-face coloring and the second has
  263. per-vertex coloring.
  264.  
  265. A subtle point: the header for vertcube.off is "COFF" as you would
  266. expect but the header for facecube.off is just "OFF" because the
  267. header refers only to the structure of the vertices, not the entire
  268. file.
  269.  
  270. [geomview: 
  271. Delete everything by picking the world and hitting the Delete Object
  272. button. Now load "facecube.off" and "vertcube.off". Translate one of
  273. them away from the center so that you can see what you're doing.
  274. Switch both Polylists between Constant, Flat, and Smooth Shading
  275. modes.
  276.  
  277. Shading is done according to light sources that you have control over.
  278. To play with the lights, open the Light panel by clicking on the Light
  279. line in the More Panels browser. When you hit the Show Lights button,
  280. you will see light beams that you can drag around to move the lights.
  281. You can also add, delete, change the intensity of, and change the
  282. color of lights.
  283. ]
  284.  
  285.  
  286.                 MESH
  287.  
  288. The vertices of a Mesh file are connected in a rectangular grid.
  289.  
  290. tent.mesh:
  291. CMESH
  292. 3 3
  293. 0 0 0  1 0 0 1       1 0 1  0 1 0 1        2 0 0  0 0 1 1
  294. 0 1 0  1 0 0 1       1 1 1  0 1 0 1        2 1 0  0 0 1 1
  295. 0 2 0  1 0 0 1       1 2 1  0 1 0 1        2 2 0  0 0 1 1
  296.  
  297. The "CMESH" header tells us that this is a Mesh file and each vertex
  298. contains both point and color information.  The second line means that
  299. both the u and v dimensions of the mesh are 3, so there will be 3*3 =
  300. 9 vertices. Each vertex that's not on an outer edge is connected to
  301. its 4 surrounding neighbots by an edge. In "tent.mesh", only the
  302. point (1,1,1) is an inside point. The 9 vertices, when named (u,v),
  303. are specified in v-major order, just like an array in C:
  304.  
  305. (0,0)---(1,0)---(2,0)   
  306.   |      |      |
  307. (0,1)---(1,1)---(2,1)
  308.   |      |      |
  309. (0,2}---(1,2)---(2,2)
  310.  
  311. [geomview:
  312. Delete everything and load "tent.mesh". Go into Smooth Shading mode to
  313. see each vertex with its own color so that it's obvious how the points in
  314. the file correspond with the image in the viewer.
  315. ]
  316.  
  317. If you want the mesh to be closed along either (or both) of the u or v
  318. edges, insert either a "u" or "v" in the header just before the
  319. "MESH".
  320.     
  321. "wraptent.mesh" 
  322. CuMESH
  323. 3 3
  324. 0 0 0  1 0 0 1       1 0 1  0 1 0 1        2 0 0  0 0 1 1
  325. 0 1 0  1 0 0 1       1 1 1  0 1 0 1        2 1 0  0 0 1 1
  326. 0 2 0  1 0 0 1       1 2 1  0 1 0 1        2 2 0  0 0 1 1
  327.  
  328. [geomview: 
  329. Load "wraptent.mesh" and compare the two Meshes, translating them
  330. apart from each other as necessary.
  331. ]
  332.  
  333. There's an extremely efficient way to describe a mesh when the x and y
  334. coordinates match the u and v coordinates of every point.
  335.  
  336. "ztent.mesh":
  337. ZMESH
  338. 3 3
  339. 0 1 0
  340. 0 1 0
  341. 0 1 0
  342.  
  343. "ztent.mesh" is exactly the same shape as "tent.mesh", although its
  344. vertices don't have any colors. The header "ZMESH" means that only
  345. the z-coordinate of each point is specified and the x and y
  346. coordinates of each point are set equal to its (u,v) position in the
  347. grid.
  348.  
  349. [geomview:
  350. Load "ztent.mesh" to verify that it's really the same shape as "tent.mesh"
  351. ]
  352.  
  353.  
  354.  
  355.                 VECT
  356.  
  357. A Vect is a collection of polylines, which are lines with 1 or more
  358. vertices. Here's a file specifying an "X" and the x-axis in red, a "Y"
  359. and the y-axis in green, and a "Z" and the z-axis in blue.
  360.  
  361. "xyz.vect":
  362. VECT
  363. 8 19 3
  364. 2 2 2 2 2 3 2 4 
  365. 1 0 0 1 0 0 1 0
  366.  
  367. 0 0 0  1 0 0
  368. 1 -.05 .05   1  .05 .25
  369. 1  .05 .05   1 -.05 .25
  370.  
  371. 0 0 0  0 1 0
  372. -.05 1 .25   0  1   .15
  373.  .05 1 .25   0  1   .15   0  1  .05
  374.  
  375. 0 0 0  0 0 1
  376. -.05 .25 1  .05 .25 1   -.05 .05 1   .05  .05  1
  377.  
  378. 1 0 0 1
  379. 0 1 0 1
  380. 0 .6 1 1
  381.  
  382. The header is always "VECT": no letters can be tacked on the front.
  383. The second line means that there are 8 polylines, which have a total
  384. of 19 vertices and 3 colors. There is no indexing into a list of
  385. vertices like a polylist: every single vertex must be specified
  386. separately. The third line lists the number of vertices in each
  387. polyline. In "xyz.vect", the only polylines with more than 2 vertices
  388. are the upper part of the "Y", which has 3, and the "Z", which has 4.
  389. The fourth line lists the number of colors in each polyline.  When a
  390. polyline has no colors it inherits the previously set color.  Next
  391. come the 19 vertices: only points are allowed. Finally, the 3 colors
  392. are given on the last three lines.
  393.  
  394. [geomview: 
  395. Delete everything, load and look at "xyz.vect". Do the same thing for
  396. all the remaining examples.
  397. ]
  398.  
  399.                 BEZ
  400.  
  401. For those who already understand how to create parametric surface
  402. patches, the syntax of Bezier surface patches is described in the OOGL
  403. man page. The art of constructing parametric surfaces is not easily
  404. explained: thus, it is beyond the scope of this tutorial to discuss
  405. them.
  406.  
  407.  
  408. Lists and Insts are complex Geoms that can be used to create a
  409. hierarchical tree of objects. 
  410.  
  411.                 LIST
  412.  
  413. A List is just a collection of other Geoms.
  414.  
  415. "ref.list":
  416. LIST
  417. < xyz.vect
  418. < dodec.quad
  419. { = QUAD -1 -1 0   1 -1 0  1 1 0  -1 1 0}
  420.  
  421.  
  422. The header is always exactly "LIST". The first two subgeoms refer to
  423. other files, using the syntax " < filename ". We have omitted the
  424. optional surrounding braces.  The third is a literal, or in-line,
  425. object. Although this particular syntax would still work if we left
  426. off the surrounding braces and equal sign, very similar syntax would
  427. not so we follow the "when in doubt, use braces" rule.
  428.  
  429. [geomview:
  430. Geomview looks for filenames in the current directory, the pathname in
  431. the GEOMDATA environment variable, and the same directory as the file
  432. that it's currently reading. 
  433. ]
  434.  
  435.                 INST
  436.  
  437. An Inst is one or more 4x4 transforms applied to another Geom.  These
  438. matrices can represent all of the 3D transformations such as rotation,
  439. translation, scaling, shearing and perspective.  We use 4x4 matrices
  440. instead of 3x3 matrices so that we can use homogenous coordinates and
  441. concatenate all transformations without treating translations as
  442. special cases that require adding instead of multiplying.  4x4
  443. matrices can also be used for such operations such as 4D rotation or
  444. projective hyperbolic transformations. A linear algebra or computer
  445. graphics textbook is a good place to start if you are unfamiliar with
  446. these ideas.
  447.  
  448. "ref.inst":
  449. INST
  450. unit { < ref.list }
  451. tlist { = 
  452. TLIST
  453.  1 0 0 0
  454.  0 1 0 0
  455.  0 0 1 0
  456.  2 0 0 1
  457.  
  458.  1 0 0 0
  459.  0 1 0 0
  460.  0 0 1 0
  461.  0 2 0 1
  462.  
  463.  1 0 0 0
  464.  0 1 0 0
  465.  0 0 1 0
  466.  0 0 2 1
  467.  
  468.  1 0 0 0
  469.  0 1 0 0
  470.  0 0 1 0
  471.  0 0 0 1
  472. }
  473.  
  474. The header is always exactly "INST". The value following the "unit"
  475. keyword is a filename reference to "ref.list", which is the List we
  476. saw above.  It could also be an in-line Geom or a handle. We surround
  477. the value with braces to avoid ambiguity.
  478.  
  479. The value of the "tlist" keyword is an in-line TList. It could also be
  480. a filename reference or a handle. (Don't worry about what a handle is,
  481. the documentation hasn't been written yet.) A TList is actually a
  482. full-fledged Geom, but we don't ever load a file like "foo.tlist" into
  483. the viewer because TLists are just a collection of transforms with no
  484. associated subgeom, so there's nothing to see.
  485.  
  486. A transform is exactly 16 numbers. The first three are a translations:
  487. 2 units in the x, y and z directions, respectively. The last is just
  488. the identity. The length of the TList is the number of instantiations
  489. of the unit: in this case, 4.
  490.  
  491. If we could not use instantiation, we would have had to compute 4
  492. entirely new Geoms, since the actual points in space of an object are
  493. different if you move it. Since the unit of an Inst can be another
  494. Inst, you can build up a complex hierarchy. For instance, to build a
  495. solar system you only need to generate one sphere. All the planets can be
  496. scaled and translated instantiations of that single Geom.
  497.  
  498.  
  499. "warp.inst":
  500. INST
  501. transform {
  502.         1 0 0 0
  503.         0 9 0 0
  504.         0 0 3 0
  505.         0 0 0 1
  506. }
  507. unit { < dodec.off }
  508.  
  509. This Inst has a single transform instead of a list of them. Thus we
  510. use the keyword "transform" instead of "tlist". A transform is not a
  511. Geom, so there is no header before the 16 numbers. We could also have
  512. a handle here.  (Don't worry about what a handle is, the documentation
  513. hasn't been written yet.)  Finally, we have "dodec.off" as our unit.
  514. The order of the unit and the TList/transform is irrelevant.
  515.  
  516.  
  517. Postscripts:
  518.  
  519. OOGL:
  520.  
  521. This tutorial only deals with ASCII OOGL files and utterly ignores
  522. binary files. See the OOGL man page for details.
  523.  
  524. Appearances (which can appear in OOGL files) are not yet documented.
  525. Stay tuned.
  526.  
  527. White space in OOGL files is mostly for the benefit of human readers.
  528. "ZMESH 3 3 0 1 0 0 1 0 0 1 0" is a legal OOGL file.  The only
  529. exception is that there cannot be a line break between the last vertex
  530. index for a Polylist face and the next 4 color floats.
  531.  
  532. geomview: 
  533.  
  534. When a Geom is loaded, it is automatically normalized to fit inside a
  535. unit cube centered around the origin. The default camera viewpoint is
  536. at {0,0,-3} looking toward the origin. To see the unaltered size and
  537. position of an object, pick the None line in the Normalization browser
  538. on the Obscure panel. In general it doesn't matter what the coordinate
  539. range of an object is as long as the entire file is consistent: {0,1},
  540. {-1,1}, {0,100}, {-1000,-500}, {17,36} are all valid ranges.
  541.  
  542.  
  543.